/***********************************************************************
    filename:   ImagerySection.h
    created:    Mon Jun 13 2005
    author:     Paul D Turner <paul@cegui.org.uk>
*************************************************************************/

#ifndef _hgeImagerySection_h_
#define _hgeImagerySection_h_

#include "renderers/ImageryComponent.h"
#include "renderers/TextComponent.h"

#if defined(_MSC_VER)
#	pragma warning(push)
#	pragma warning(disable : 4251)
#endif

/*!
\brief
    Class that encapsulates a re-usable collection of imagery specifications.
*/
class ImagerySection
{
public:
    /*!
    \brief
        Constructor.
    */
    ImagerySection();

    /*!
    \brief
        ImagerySection constructor.  Name must be supplied, masterColours are set to 0xFFFFFFFF by default.

    \param name
        Name of the new ImagerySection.
    */
    ImagerySection(const String& name);

    /*!
    \brief
        Render the ImagerySection.

    \param srcWindow
        Window object to be used when calculating pixel values from BaseDim values.

    \param modColours
        ColourRect specifying colours to be modulated with the ImagerySection's master colours.  May be 0.

    \return
        Nothing.
    */
    void render(Window& srcWindow, const ColourRect* modColours = 0, const hgeRect* clipper = 0, bool clipToDisplay = false) const;

    /*!
    \brief
        Render the ImagerySection.

    \param srcWindow
        Window object to be used when calculating pixel values from BaseDim values.

    \param baseRect
        hgeRect object to be used when calculating pixel values from BaseDim values.

    \param modColours
        ColourRect specifying colours to be modulated with the ImagerySection's master colours.  May be 0.

    \return
        Nothing.
    */
    void render(Window& srcWindow, const hgeRect& baseRect, const ColourRect* modColours = 0, const hgeRect* clipper = 0, bool clipToDisplay = false) const;

    /*!
    \brief
        Add an ImageryComponent to this ImagerySection.

    \param img
        ImageryComponent to be added to the section (a copy is made)

    \return
        Nothing
    */
    void addImageryComponent(const ImageryComponent& img);

    /*!
    \brief
        Clear all ImageryComponents from this ImagerySection.

    \return
        Nothing
    */
    void clearImageryComponents();

    /*!
    \brief
        Add a TextComponent to this ImagerySection.

    \param text
        TextComponent to be added to the section (a copy is made)

    \return
        Nothing
    */
    void addTextComponent(const TextComponent& text);

    /*!
    \brief
        Clear all TextComponents from this ImagerySection.

    \return
        Nothing
    */
    void clearTextComponents();

    /*!
    \brief
        Return the current master colours set for this ImagerySection.

    \return
        ColourRect describing the master colour values in use for this ImagerySection.
    */
    const ColourRect& getMasterColours() const;

    /*!
    \brief
        Set the master colours to be used for this ImagerySection.

    \param cols
        ColourRect describing the colours to be set as the master colours for this ImagerySection.

    \return
        Nothing.
    */
    void setMasterColours(const ColourRect& cols);

    /*!
    \brief
        Return the name of this ImagerySection.

    \return
        String object holding the name of the ImagerySection.
    */
    const String& getName() const;

    /*!
    \brief
        Set the name of the property where master colour values can be obtained.

    \param property
        String containing the name of the property.

    \return
        Nothing.
    */
    void setMasterColoursPropertySource(const String& property);

    /*!
    \brief
        Set whether the master colours property source represents a full ColourRect.

    \param setting
        - true if the master colours property will access a ColourRect object.
        - false if the master colours property will access a colour object.

    \return
        Nothing.
    */
    void setMasterColoursPropertyIsColourRect(bool setting = true);

    /*!
    \brief
        Return smallest hgeRect that could contain all imagery within this section.
    */
    hgeRect getBoundingRect(const Window& wnd) const;

    /*!
    \brief
        Return smallest hgeRect that could contain all imagery within this section.
    */
    hgeRect getBoundingRect(const Window& wnd, const hgeRect& rect) const;


protected:
    /*!
    \brief
        Helper method to initialise a ColourRect with appropriate values according to the way the
        ImagerySection is set up.

        This will try and get values from multiple places:
            - a property attached to \a wnd
            - or the integral d_masterColours value.
    */
    void initMasterColourRect(const Window& wnd, ColourRect& cr) const;

private:
    typedef std::vector<ImageryComponent> ImageryList;
    typedef std::vector<TextComponent> TextList;

    String       d_name;				 //!< Holds the name of the ImagerySection.
    ColourRect   d_masterColours;		 //!< Naster colours for the the ImagerySection (combined with colours of each ImageryComponent).
    ImageryList  d_images;				 //!< Collection of ImageryComponent objects to be drawn for this ImagerySection.
    TextList     d_texts;				 //!< Collection of TextComponent objects to be drawn for this ImagerySection.
    String       d_colourPropertyName;   //!< name of property to fetch colours from.
    bool         d_colourProperyIsRect;  //!< true if the colour property will fetch a full ColourRect.
};

#if defined(_MSC_VER)
#	pragma warning(pop)
#endif

#endif  // end of guard _hgeImagerySection_h_
